/**
 * Software License, Version 1.0
 * 
 * Copyright 2003 The Trustees of Indiana University.  All rights reserved.
 * 
 *
 *Redistribution and use in source and binary forms, with or without 
 *modification, are permitted provided that the following conditions are met:
 *
 *1) All redistributions of source code must retain the above copyright notice,
 * the list of authors in the original source code, this list of conditions and
 * the disclaimer listed in this license;
 *2) All redistributions in binary form must reproduce the above copyright 
 * notice, this list of conditions and the disclaimer listed in this license in
 * the documentation and/or other materials provided with the distribution;
 *3) Any documentation included with all redistributions must include the 
 * following acknowledgement:
 *
 *"This product includes software developed by the Community Grids Lab. For 
 * further information contact the Community Grids Lab at 
 * http://communitygrids.iu.edu/."
 *
 * Alternatively, this acknowledgement may appear in the software itself, and 
 * wherever such third-party acknowledgments normally appear.
 * 
 *4) The name Indiana University or Community Grids Lab or NaradaBrokering, 
 * shall not be used to endorse or promote products derived from this software 
 * without prior written permission from Indiana University.  For written 
 * permission, please contact the Advanced Research and Technology Institute 
 * ("ARTI") at 351 West 10th Street, Indianapolis, Indiana 46202.
 *5) Products derived from this software may not be called NaradaBrokering, 
 * nor may Indiana University or Community Grids Lab or NaradaBrokering appear
 * in their name, without prior written permission of ARTI.
 * 
 *
 * Indiana University provides no reassurances that the source code provided 
 * does not infringe the patent or any other intellectual property rights of 
 * any other entity.  Indiana University disclaims any liability to any 
 * recipient for claims brought by any other entity based on infringement of 
 * intellectual property rights or otherwise.  
 *
 *LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO 
 *WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES
 *NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF 
 *INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS. 
 *INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS", 
 *"VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE.  
 *LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR 
 *ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION 
 *GENERATED USING SOFTWARE.
 */
package cgl.narada.wsinfra.wsr.storage;

import javax.xml.namespace.QName;

import cgl.narada.wsinfra.wsr.storage.impl.WsrGroupTerminationInfoImpl;
import cgl.narada.wsinfra.wsr.storage.impl.WsrStorageWidgetImpl;


/** This class pertains to storage operations related to the WSR protocol. 
    These include functions such as
    <br>(a) Storage of sent/received messages over a group.
    <br>(b) Processing acknowledgements for a given group from over a set
    of sequence numbers.
    <br>(c) Retrieving messages for retransmissions.
    <br>(d) Retrieving the message numbers for a given group that have
    not been acknowledged yet.
    <br>(e) Retrieval of the last message number for a group.

    @author sima patel
    $Date: 2005/04/15 15:23:05 $
    $Revision: 1.6 $
*/

public interface WsrProtocolStorageOperations {

  
    /** Processes a set of acknowledgements received on a given group.
    This method throws an exception under the following conditions.
    <br> The group specified by groupId is an unknown one.
    <br> One or more of the acknowledgements refer to non-existent sequence numbers.
    <br> Storage related problems */
    public void processAcknowledgementsOnGroup(String groupId,
					       long[] ackSequenceNumbers) 
                throws WsrStorageException;
   
    /** Processes an acknowledgement received on a given group for a specific
    sequence number.
    This method throws an exception under the following conditions.
    <br> The group specified by groupId is an unknown one.
    <br> The acknowledgement refers to non-existent sequence number  
    <br> Storage related problems */
    public void processAcknowledgementOnGroup(String groupId,
					      long ackSequenceNumber) 
                throws WsrStorageException;
  
  
    /** Processes Fault received on a given group for a specific
    sequence number.
    This method throws an exception under the following conditions.
    <br> The group specified by groupId is an unknown one.
    <br> The fault refers to non-existent sequence number  
    <br> Storage related problems */
    public void processFaultOnGroup(String groupId,
			            long sequenceNumber, QName fault) 
                throws WsrStorageException;
  
  
    /** Retrieves the list of sequence numbers that have NOT been acknowledged, 
    up until the sequence number specified in <i>upUntilSequenceNumber</i>
    This method throws an exception under the following conditions.
    <br> The group specified by groupId is an unknown one.
    <br> The specified sequence number is a non-existent one. 
    <br> Storage related problems  */
    public long[] getUnacknowledgedSequenceNumbers(String groupId,
						   long upUntilSequenceNumber)
                  throws WsrStorageException;

    /** Retrieves the list of sequence numbers that have NOT been acknowledged 
    and faulted for a given group. This
    method throws an exception if the group specified by 
    <i>groupId</i> is an unknown one or if there are other 
    storage problems. */
    public long[] getUnacknowledgedSequenceNumbers(String groupId)
                  throws WsrStorageException;
  
    /** Retrieves the list of sequence numbers that have NOT been Delivered, 
    and have sequenceNumber greater than specified sequenceNumber
    This method throws an exception under the following conditions.
    <br> The group specified by groupId is an unknown one.
    <br> Storage related problems  */
    public long[] getUnDeliveredSequenceNumbers(String groupId,
						   long sequenceNumber)
                  throws WsrStorageException;   
    
    
    /** Retrieves the list of sequence numbers that have NOT been Delivered
    for a given group.This
    method throws an exception if the group specified by 
    <i>groupId</i> is an unknown one or if there are other 
    storage problems. */
    public long[] getUnDeliveredSequenceNumbers(String groupId)
                  throws WsrStorageException;
  

    /** Retrieves the list of sequence numbers that have been acknowledged
    This method throws WsrStorageException.*/
    public long[] getAcknowledgedSequenceNumbers(String groupId) 
                  throws WsrStorageException;
  
    /** Retrieves the list of all sequence numbers */
    public long[] getSequenceNumbers(String groupId) 
                  throws WsrStorageException;

    /** Retrieves the sequence number that was last assigned on a given
    group. This method throws an exception if the group
    specified by groupId is an unknown one or if there are 
    storage related problems.  */
    public long getSequenceNumberLastAssigned(String groupId)
                throws WsrStorageException;   
    

    /** Store a WSR message to storage. This method throws an exception if 
    there are storage related problems. */
    public void store(WsrStorageWidgetImpl widget)
                throws WsrStorageException;
  


    /** Checks to see if there are widgets that have been stored for the 
    group in question. */
    public boolean hasStoredElements(String groupId)
                   throws WsrStorageException;


    /** Check to see if there is a widget that has been stored for a specific
    sequence number in a given group */
    public boolean hasStoredElement(String groupId, long sequenceNumber) 
                   throws WsrStorageException;
    
    /** Retrieves a stored WsrStorageWidget from storage. This method throws an
    exception under the following conditions.
    <br> The group specified by groupId is an unknown one.
    <br> The specified sequence number is a non-existent one. 
    <br> Storage related problems  */
    public WsrStorageWidgetImpl getStoredElement(String groupId, 
		                                 long sequenceNumber) 
                                throws WsrStorageException;
    
    /** Retrieves stored WsrStorageWidgets from storage. This method throws an
    exception under the following conditions.
    <br> The group specified by groupId is an unknown one.
    <br> One or more of the specified sequence numbers are non-existent. 
    <br> Storage related problems */
    public WsrStorageWidgetImpl[] getStoredElements(String groupId,
		                                    long[]sequenceNumbers) 
                                  throws WsrStorageException;
  
    /** Removes stored WsrStorageWidget from storage. This method throws an
    exception under the following conditions.
    <br> The group specified by groupId is an unknown one.
    <br> Storage related problems */
    public void deleteStoredElement(String groupId, long sequenceNumber) 
                throws WsrStorageException;

  
    /** Stores the GroupTerminationInfo object.
    This method stores the groupTerminationInfo object in storage
    If groupId in groupTerminationInfo object is already exist
    then it updates the GroupTerminationInfo Object in storage. 
    This method throws exception if 
    <br> Storage related problems 
    */
    public void storeGroupTerminationInfo(WsrGroupTerminationInfoImpl 
                                                           groupTerminationInfo)
                throws WsrStorageException;
  
    /** Gets the Status of the Message from storage*/
    public byte getMessageStatus(String groupId, long sequenceNumber)
                throws WsrStorageException;
  
    /** Gets the Fault associate with the message if message is faulted from storage*/
    public String getMessageFault(String groupId, long sequenceNumber)
                  throws WsrStorageException;
  
    /** Retrieves the GroupTerminationInfo object.
    This method retrieves the groupTerminationInfo object for particular groupId from storage
    This method throws an exception under the
    following circumstances
    <br> The groupId in the GroupTerminationInfo not exists.
    <br> Storage related problems 
    */
    public WsrGroupTerminationInfoImpl getGroupTerminationInfo(String groupId)
                                       throws WsrStorageException;
  
    /** Delete the GroupTerminationInfo object.
    This method deletes the groupTerminationInfo object for particular groupId 
    from storage. This method throws an exception under the following circumstances
    <br> The groupId in the GroupTerminationInfo not exists.
    <br> Storage related problems 
    */
    public void deleteGroupTerminationInfo(String groupId)
                throws WsrStorageException;
  
  
    /** Reset the Retranmission Time associated with the message */
    public void resetRetransmissionTime(WsrStorageWidgetImpl wsrStorageWidgetImpl,
			                long retransmissionTime)
                throws WsrStorageException;
    /** Reset the Number Of Retries associated with the retransmission of the message*/
    public void resetNumberOfRetries(WsrStorageWidgetImpl wsrStorageWidgetImpl,
    		                         byte numberOfRetries)
                throws WsrStorageException;

}